/*!
 * \file BoostMappingFile.hpp
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief 基于boost::interprocess的内存映射文件封装类
 * 
 * \details 提供高效的内存映射文件操作功能，包括：
 *          - 文件到内存的映射管理
 *          - 支持只读、只写、读写多种访问模式
 *          - 自动内存管理和资源清理
 *          - 高性能的文件数据访问
 *          
 *          内存映射技术允许将文件内容直接映射到进程的虚拟内存空间，
 *          避免了传统文件读写的系统调用开销，特别适用于大文件的
 *          随机访问和高频数据处理场景。
 */
#pragma once
#include <boost/filesystem.hpp>
#include <boost/interprocess/file_mapping.hpp>
#include <boost/interprocess/mapped_region.hpp>

/*!
 * \brief Boost内存映射文件封装类
 * 
 * \details 基于boost::interprocess实现的高效文件内存映射，特点：
 *          - 零拷贝文件访问，直接操作内存地址
 *          - 支持多种访问模式（只读、只写、读写）
 *          - 自动资源管理，异常安全
 *          - 提供文件同步和缓存控制
 *          - 跨平台兼容性
 *          
 *          适用场景：
 *          - 大文件的快速读写
 *          - 数据文件的随机访问
 *          - 多进程间的文件共享
 *          - 高性能数据处理
 */
class BoostMappingFile
{
public:
	/// 构造函数，初始化为空映射
	BoostMappingFile()
	{
		_file_map=NULL;
		_map_region=NULL;
	}

	/// 析构函数，自动关闭映射
	~BoostMappingFile()
	{
		close();
	}

	/*!
	 * \brief 关闭文件映射，释放资源
	 * 
	 * \details 按正确顺序释放映射区域和文件映射对象，
	 *          确保资源安全释放，避免内存泄漏
	 */
	void close()
	{
		if(_map_region!=NULL)
			delete _map_region;

		if(_file_map!=NULL)
			delete _file_map;

		_file_map=NULL;
		_map_region=NULL;
	}

	/*!
	 * \brief 同步内存映射数据到磁盘
	 * 
	 * \details 将内存中修改的数据强制写入磁盘文件，
	 *          确保数据持久化。在程序崩溃或异常退出时
	 *          可以保证数据不丢失
	 */
	void sync()
	{
		if(_map_region)
			_map_region->flush();
	}

	/*!
	 * \brief 获取映射内存地址
	 * \return 映射的内存起始地址，失败返回NULL
	 * 
	 * \details 返回的地址可以直接进行内存操作，
	 *          如memcpy、指针访问等，提供最高效的文件访问方式
	 */
	void *addr()
	{
		if(_map_region)
			return _map_region->get_address();
		return NULL;
	}

	/*!
	 * \brief 获取映射区域大小
	 * \return 映射的字节数，失败返回0
	 * 
	 * \details 返回实际映射的文件大小，
	 *          可用于边界检查和内存操作范围控制
	 */
	size_t size()
	{
		if(_map_region)
			return _map_region->get_size();
		return 0;
	}

	/*!
	 * \brief 映射文件到内存
	 * \param filename 要映射的文件路径
	 * \param mode 文件访问模式，默认读写
	 * \param mapmode 映射访问模式，默认读写
	 * \param zeroother 保留参数，当前未使用
	 * \return 成功返回true，失败返回false
	 * 
	 * \details 执行文件到内存的映射操作：
	 *          1. 检查文件是否存在
	 *          2. 创建文件映射对象
	 *          3. 创建映射区域对象
	 *          4. 建立内存映射关系
	 *          
	 *          注意：文件必须已存在，否则映射失败
	 */
	bool map(const char *filename,
		int mode=boost::interprocess::read_write,
		int mapmode=boost::interprocess::read_write,bool zeroother=true)
	{
		if (!boost::filesystem::exists(filename))
		{
			return false;
		}
		_file_name = filename;

		_file_map = new boost::interprocess::file_mapping(filename,(boost::interprocess::mode_t)mode);
		if(_file_map==NULL)
			return false;

		_map_region = new boost::interprocess::mapped_region(*_file_map,(boost::interprocess::mode_t)mapmode);
		if(_map_region==NULL)
		{
			delete _file_map;
			return false;
		}

		return true;
	}

	/*!
	 * \brief 获取映射的文件名
	 * \return 文件路径字符串
	 */
	const char* filename()
	{
		return _file_name.c_str();
	}

	/*!
	 * \brief 检查映射是否有效
	 * \return 有效返回true，无效返回false
	 */
	bool valid() const
	{
		return _file_map != NULL;
	}

private:
	std::string _file_name;								///< 映射的文件名
	boost::interprocess::file_mapping *_file_map;		///< boost文件映射对象
	boost::interprocess::mapped_region *_map_region;	///< boost映射区域对象
};

